home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1999 August / SGI Freeware 1999 August.iso / dist / fw_xemacs.idb / usr / freeware / lib / xemacs-20.4 / info / texinfo.info-5.z / texinfo.info-5
Encoding:
GNU Info File  |  1998-05-21  |  49.5 KB  |  1,445 lines
  1. This is Info file ../info/texinfo.info, produced by Makeinfo version
  2. 1.68 from the input file texinfo.texi.
  3.  
  4. INFO-DIR-SECTION Texinfo documentation system
  5. START-INFO-DIR-ENTRY
  6. * Texinfo: (texinfo).           The GNU documentation format.
  7. * install-info: (texinfo)Invoking install-info. Updating info/dir entries.
  8. * texi2dvi: (texinfo)Format with texi2dvi.      Printing Texinfo documentation.
  9. * texindex: (texinfo)Format with tex/texindex.  Sorting Texinfo index files.
  10. * makeinfo: (texinfo)makeinfo Preferred.        Translate Texinfo source.
  11. END-INFO-DIR-ENTRY
  12.  
  13.   This file documents Texinfo, a documentation system that can produce
  14. both on-line information and a printed manual from a single source file.
  15.  
  16.   Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97 Free Software
  17. Foundation, Inc.
  18.  
  19.   This is the second edition of the Texinfo documentation,
  20. and is consistent with version 2 of `texinfo.tex'.
  21.  
  22.   Permission is granted to make and distribute verbatim copies of this
  23. manual provided the copyright notice and this permission notice are
  24. preserved on all copies.
  25.  
  26.   Permission is granted to copy and distribute modified versions of this
  27. manual under the conditions for verbatim copying, provided that the
  28. entire resulting derived work is distributed under the terms of a
  29. permission notice identical to this one.
  30.  
  31.   Permission is granted to copy and distribute translations of this
  32. manual into another language, under the above conditions for modified
  33. versions, except that this permission notice may be stated in a
  34. translation approved by the Free Software Foundation.
  35.  
  36. 
  37. File: texinfo.info,  Node: Indicating,  Next: Emphasis,  Prev: Marking Text,  Up: Marking Text
  38.  
  39. Indicating Definitions, Commands, etc.
  40. ======================================
  41.  
  42.   Texinfo has commands for indicating just what kind of object a piece
  43. of text refers to.  For example, metasyntactic variables are marked by
  44. `@var', and code by `@code'.  Since the pieces of text are labelled by
  45. commands that tell what kind of object they are, it is easy to change
  46. the way the Texinfo formatters prepare such text.  (Texinfo is an
  47. *intentional* formatting language rather than a *typesetting*
  48. formatting language.)
  49.  
  50.   For example, in a printed manual, code is usually illustrated in a
  51. typewriter font; `@code' tells TeX to typeset this text in this font.
  52. But it would be easy to change the way TeX highlights code to use
  53. another font, and this change would not effect how keystroke examples
  54. are highlighted.  If straight typesetting commands were used in the body
  55. of the file and you wanted to make a change, you would need to check
  56. every single occurrence to make sure that you were changing code and
  57. not something else that should not be changed.
  58.  
  59. * Menu:
  60.  
  61. * Useful Highlighting::         Highlighting provides useful information.
  62. * code::                        How to indicate code.
  63. * kbd::                         How to show keyboard input.
  64. * key::                         How to specify keys.
  65. * samp::                        How to show a literal sequence of characters.
  66. * var::                         How to indicate a metasyntactic variable.
  67. * file::                        How to indicate the name of a file.
  68. * dfn::                         How to specify a definition.
  69. * cite::                        How to refer to a book that is not in Info.
  70. * url::                         How to indicate a world wide web reference.
  71. * email::                       How to indicate an electronic mail address.
  72.  
  73. 
  74. File: texinfo.info,  Node: Useful Highlighting,  Next: code,  Prev: Indicating,  Up: Indicating
  75.  
  76. Highlighting Commands are Useful
  77. --------------------------------
  78.  
  79.   The highlighting commands can be used to generate useful information
  80. from the file, such as lists of functions or file names.  It is
  81. possible, for example, to write a program in Emacs Lisp (or a keyboard
  82. macro) to insert an index entry after every paragraph that contains
  83. words or phrases marked by a specified command.  You could do this to
  84. construct an index of functions if you had not already made the entries.
  85.  
  86.   The commands serve a variety of purposes:
  87.  
  88. `@code{SAMPLE-CODE}'
  89.      Indicate text that is a literal example of a piece of a program.
  90.  
  91. `@kbd{KEYBOARD-CHARACTERS}'
  92.      Indicate keyboard input.
  93.  
  94. `@key{KEY-NAME}'
  95.      Indicate the conventional name for a key on a keyboard.
  96.  
  97. `@samp{TEXT}'
  98.      Indicate text that is a literal example of a sequence of
  99.      characters.
  100.  
  101. `@var{METASYNTACTIC-VARIABLE}'
  102.      Indicate a metasyntactic variable.
  103.  
  104. `@url{UNIFORM-RESOURCE-LOCATOR}'
  105.      Indicate a uniform resource locator for the World Wide Web.
  106.  
  107. `@file{FILE-NAME}'
  108.      Indicate the name of a file.
  109.  
  110. `@email{EMAIL-ADDRESS[, DISPLAYED-TEXT]}'
  111.      Indicate an electronic mail address.
  112.  
  113. `@dfn{TERM}'
  114.      Indicate the introductory or defining use of a term.
  115.  
  116. `@cite{REFERENCE}'
  117.      Indicate the name of a book.
  118.  
  119. 
  120. File: texinfo.info,  Node: code,  Next: kbd,  Prev: Useful Highlighting,  Up: Indicating
  121.  
  122. `@code'{SAMPLE-CODE}
  123. --------------------
  124.  
  125.   Use the `@code' command to indicate text that is a piece of a program
  126. and which consists of entire syntactic tokens.  Enclose the text in
  127. braces.
  128.  
  129.   Thus, you should use `@code' for an expression in a program, for the
  130. name of a variable or function used in a program, or for a keyword.
  131. Also, you should use `@code' for the name of a program, such as `diff',
  132. that is a name used in the machine. (You should write the name of a
  133. program in the ordinary text font if you regard it as a new English
  134. word, such as `Emacs' or `Bison'.)
  135.  
  136.   Use `@code' for environment variables such as `TEXINPUTS', and other
  137. variables.
  138.  
  139.   Use `@code' for command names in command languages that resemble
  140. programming languages, such as Texinfo or the shell.  For example,
  141. `@code' and `@samp' are produced by writing `@code{@@code}' and
  142. `@code{@@samp}' in the Texinfo source, respectively.
  143.  
  144.   Note, however, that you should not use `@code' for shell options such
  145. as `-c' when such options stand alone. (Use `@samp'.)  Also, an entire
  146. shell command often looks better if written using `@samp' rather than
  147. `@code'.  In this case, the rule is to choose the more pleasing format.
  148.  
  149.   It is incorrect to alter the case of a word inside an `@code' command
  150. when it appears at the beginning of a sentence.  Most computer
  151. languages are case sensitive.  In C, for example, `Printf' is different
  152. from the identifier `printf', and most likely is a misspelling of it.
  153. Even in languages which are not case sensitive, it is confusing to a
  154. human reader to see identifiers spelled in different ways.  Pick one
  155. spelling and always use that.  If you do not want to start a sentence
  156. with a command written all in lower case, you should rearrange the
  157. sentence.
  158.  
  159.   Do not use the `@code' command for a string of characters shorter
  160. than a syntactic token.  If you are writing about `TEXINPU', which is
  161. just a part of the name for the `TEXINPUTS' environment variable, you
  162. should use `@samp'.
  163.  
  164.   In particular, you should not use the `@code' command when writing
  165. about the characters used in a token; do not, for example, use `@code'
  166. when you are explaining what letters or printable symbols can be used
  167. in the names of functions.  (Use `@samp'.)  Also, you should not use
  168. `@code' to mark text that is considered input to programs unless the
  169. input is written in a language that is like a programming language.
  170. For example, you should not use `@code' for the keystroke commands of
  171. GNU Emacs (use `@kbd' instead) although you may use `@code' for the
  172. names of the Emacs Lisp functions that the keystroke commands invoke.
  173.  
  174.   In the printed manual, `@code' causes TeX to typeset the argument in
  175. a typewriter face.  In the Info file, it causes the Info formatting
  176. commands to use single quotation marks around the text.
  177.  
  178.   For example,
  179.  
  180.      Use @code{diff} to compare two files.
  181.  
  182. produces this in the printed manual:
  183.  
  184.      Use `diff' to compare two files.
  185.  
  186. 
  187. File: texinfo.info,  Node: kbd,  Next: key,  Prev: code,  Up: Indicating
  188.  
  189. `@kbd'{KEYBOARD-CHARACTERS}
  190. ---------------------------
  191.  
  192.   Use the `@kbd' command for characters of input to be typed by users.
  193. For example, to refer to the characters `M-a', write
  194.  
  195.      @kbd{M-a}
  196.  
  197. and to refer to the characters `M-x shell', write
  198.  
  199.      @kbd{M-x shell}
  200.  
  201.   The `@kbd' command has the same effect as `@code' in Info, but by
  202. default produces a different font (slanted typewriter instead of normal
  203. typewriter) in the printed manual, so users can distinguish the
  204. characters they are supposed to type from those the computer outputs.
  205.  
  206.   Since the usage of `@kbd' varies from manual to manual, you can
  207. control the font switching with the `@kbdinputstyle' command.  This
  208. command has no effect on Info output.  Write this command at the
  209. beginning of a line with a single word as an argument, one of the
  210. following:
  211. `code'
  212.      Always use the same font for `@kbd' as `@code'.
  213.  
  214. `example'
  215.      Use the distinguishing font for `@kbd' only in `@example' and
  216.      similar environments.
  217.  
  218. `example'
  219.      (the default) Always use the distinguishing font for `@kbd'.
  220.  
  221.   You can embed another @-command inside the braces of an `@kbd'
  222. command.  Here, for example, is the way to describe a command that
  223. would be described more verbosely as "press an `r' and then press the
  224. <RET> key":
  225.  
  226.      @kbd{r @key{RET}}
  227.  
  228. This produces: `r <RET>'
  229.  
  230.   You also use the `@kbd' command if you are spelling out the letters
  231. you type; for example:
  232.  
  233.      To give the @code{logout} command,
  234.      type the characters @kbd{l o g o u t @key{RET}}.
  235.  
  236. This produces:
  237.  
  238.      To give the `logout' command, type the characters `l o g o u t
  239.      <RET>'.
  240.  
  241.   (Also, this example shows that you can add spaces for clarity.  If you
  242. really want to mention a space character as one of the characters of
  243. input, write `@key{SPC}' for it.)
  244.  
  245. 
  246. File: texinfo.info,  Node: key,  Next: samp,  Prev: kbd,  Up: Indicating
  247.  
  248. `@key'{KEY-NAME}
  249. ----------------
  250.  
  251.   Use the `@key' command for the conventional name for a key on a
  252. keyboard, as in:
  253.  
  254.      @key{RET}
  255.  
  256.   You can use the `@key' command within the argument of an `@kbd'
  257. command when the sequence of characters to be typed includes one or
  258. more keys that are described by name.
  259.  
  260.   For example, to produce `C-x <ESC>' you would type:
  261.  
  262.      @kbd{C-x @key{ESC}}
  263.  
  264.   Here is a list of the recommended names for keys:
  265.  
  266.     SPC
  267.           Space
  268.  
  269.     RET
  270.           Return
  271.  
  272.     LFD
  273.           Linefeed (however, since most keyboards nowadays do not have
  274.           a Linefeed key, it might be better to call this character
  275.           `C-j'.
  276.  
  277.     TAB
  278.           Tab
  279.  
  280.     BS
  281.           Backspace
  282.  
  283.     ESC
  284.           Escape
  285.  
  286.     DEL
  287.           Delete
  288.  
  289.     SHIFT
  290.           Shift
  291.  
  292.     CTRL
  293.           Control
  294.  
  295.     META
  296.           Meta
  297.  
  298.   There are subtleties to handling words like `meta' or `ctrl' that are
  299. names of modifier keys.  When mentioning a character in which the
  300. modifier key is used, such as `Meta-a', use the `@kbd' command alone;
  301. do not use the `@key' command; but when you are referring to the
  302. modifier key in isolation, use the `@key' command.  For example, write
  303. `@kbd{Meta-a}' to produce `Meta-a' and `@key{META}' to produce <META>.
  304.  
  305. 
  306. File: texinfo.info,  Node: samp,  Next: var,  Prev: key,  Up: Indicating
  307.  
  308. `@samp'{TEXT}
  309. -------------
  310.  
  311.   Use the `@samp' command to indicate text that is a literal example or
  312. `sample' of a sequence of characters in a file, string, pattern, etc.
  313. Enclose the text in braces.  The argument appears within single
  314. quotation marks in both the Info file and the printed manual; in
  315. addition, it is printed in a fixed-width font.
  316.  
  317.      To match @samp{foo} at the end of the line,
  318.      use the regexp @samp{foo$}.
  319.  
  320. produces
  321.  
  322.      To match `foo' at the end of the line, use the regexp `foo$'.
  323.  
  324.   Any time you are referring to single characters, you should use
  325. `@samp' unless `@kbd' or `@key' is more appropriate.  Use `@samp' for
  326. the names of command-line options (except in an `@table', where `@code'
  327. seems to read more easily).  Also, you may use `@samp' for entire
  328. statements in C and for entire shell commands--in this case, `@samp'
  329. often looks better than `@code'.  Basically, `@samp' is a catchall for
  330. whatever is not covered by `@code', `@kbd', or `@key'.
  331.  
  332.   Only include punctuation marks within braces if they are part of the
  333. string you are specifying.  Write punctuation marks outside the braces
  334. if those punctuation marks are part of the English text that surrounds
  335. the string.  In the following sentence, for example, the commas and
  336. period are outside of the braces:
  337.  
  338.      In English, the vowels are @samp{a}, @samp{e},
  339.      @samp{i}, @samp{o}, @samp{u}, and sometimes
  340.      @samp{y}.
  341.  
  342. This produces:
  343.  
  344.      In English, the vowels are `a', `e', `i', `o', `u',  and sometimes
  345.      `y'.
  346.  
  347. 
  348. File: texinfo.info,  Node: var,  Next: file,  Prev: samp,  Up: Indicating
  349.  
  350. `@var'{METASYNTACTIC-VARIABLE}
  351. ------------------------------
  352.  
  353.   Use the `@var' command to indicate metasyntactic variables.  A
  354. "metasyntactic variable" is something that stands for another piece of
  355. text.  For example, you should use a metasyntactic variable in the
  356. documentation of a function to describe the arguments that are passed
  357. to that function.
  358.  
  359.   Do not use `@var' for the names of particular variables in
  360. programming languages.  These are specific names from a program, so
  361. `@code' is correct for them.  For example, the Emacs Lisp variable
  362. `texinfo-tex-command' is not a metasyntactic variable; it is properly
  363. formatted using `@code'.
  364.  
  365.   The effect of `@var' in the Info file is to change the case of the
  366. argument to all upper case; in the printed manual, to italicize it.
  367.  
  368.   For example,
  369.  
  370.      To delete file @var{filename},
  371.      type @code{rm @var{filename}}.
  372.  
  373. produces
  374.  
  375.      To delete file FILENAME, type `rm FILENAME'.
  376.  
  377. (Note that `@var' may appear inside `@code', `@samp', `@file', etc.)
  378.  
  379.   Write a metasyntactic variable all in lower case without spaces, and
  380. use hyphens to make it more readable.  Thus, the Texinfo source for the
  381. illustration of how to begin a Texinfo manual looks like this:
  382.  
  383.      \input texinfo
  384.      @@setfilename @var{info-file-name}
  385.      @@settitle @var{name-of-manual}
  386.  
  387. This produces:
  388.  
  389.      \input texinfo
  390.      @setfilename INFO-FILE-NAME
  391.      @settitle NAME-OF-MANUAL
  392.  
  393.   In some documentation styles, metasyntactic variables are shown with
  394. angle brackets, for example:
  395.  
  396.      ..., type rm <filename>
  397.  
  398. However, that is not the style that Texinfo uses.  (You can, of course,
  399. modify the sources to TeX and the Info formatting commands to output
  400. the `<...>' format if you wish.)
  401.  
  402. 
  403. File: texinfo.info,  Node: file,  Next: dfn,  Prev: var,  Up: Indicating
  404.  
  405. `@file'{FILE-NAME}
  406. ------------------
  407.  
  408.   Use the `@file' command to indicate text that is the name of a file,
  409. buffer, or directory, or is the name of a node in Info.  You can also
  410. use the command for file name suffixes.  Do not use `@file' for symbols
  411. in a programming language; use `@code'.
  412.  
  413.   Currently, `@file' is equivalent to `@samp' in its effects.  For
  414. example,
  415.  
  416.      The @file{.el} files are in
  417.      the @file{/usr/local/emacs/lisp} directory.
  418.  
  419. produces
  420.  
  421.      The `.el' files are in the `/usr/local/emacs/lisp' directory.
  422.  
  423. 
  424. File: texinfo.info,  Node: dfn,  Next: cite,  Prev: file,  Up: Indicating
  425.  
  426. `@dfn'{TERM}
  427. ------------
  428.  
  429.   Use the `@dfn' command to identify the introductory or defining use
  430. of a technical term.  Use the command only in passages whose purpose is
  431. to introduce a term which will be used again or which the reader ought
  432. to know.  Mere passing mention of a term for the first time does not
  433. deserve `@dfn'.  The command generates italics in the printed manual,
  434. and double quotation marks in the Info file.  For example:
  435.  
  436.      Getting rid of a file is called @dfn{deleting} it.
  437.  
  438. produces
  439.  
  440.      Getting rid of a file is called "deleting" it.
  441.  
  442.   As a general rule, a sentence containing the defining occurrence of a
  443. term should be a definition of the term.  The sentence does not need to
  444. say explicitly that it is a definition, but it should contain the
  445. information of a definition--it should make the meaning clear.
  446.  
  447. 
  448. File: texinfo.info,  Node: cite,  Next: url,  Prev: dfn,  Up: Indicating
  449.  
  450. `@cite'{REFERENCE}
  451. ------------------
  452.  
  453.   Use the `@cite' command for the name of a book that lacks a companion
  454. Info file. The command produces italics in the printed manual, and
  455. quotation marks in the Info file.
  456.  
  457.   (If a book is written in Texinfo, it is better to use a cross
  458. reference command since a reader can easily follow such a reference in
  459. Info.  *Note `@xref': xref.)
  460.  
  461. 
  462. File: texinfo.info,  Node: url,  Next: email,  Prev: cite,  Up: Indicating
  463.  
  464. `@url'{UNIFORM-RESOURCE-LOCATOR}
  465. --------------------------------
  466.  
  467.   Use the `@url' to indicate a uniform resource locator on the World
  468. Wide Web.  This is analogous to `@file', `@var', etc., and is purely
  469. for markup purposes.  It does not produce a link you can follow in HTML
  470. output (the `@uref' command does, *note `@uref': uref.).  It is useful
  471. for example URL's which do not actually exist.  For example:
  472.  
  473.      For example, the url might be
  474.      @url{http://host.domain.org/path}.
  475.  
  476. 
  477. File: texinfo.info,  Node: email,  Prev: url,  Up: Indicating
  478.  
  479. `@email'{EMAIL-ADDRESS[, DISPLAYED-TEXT]}
  480. -----------------------------------------
  481.  
  482.   Use the `@email' command to indicate an electronic mail address.  It
  483. takes one mandatory argument, the address, and one optional argument,
  484. the text to display (the default is the address itself).
  485.  
  486.   In Info and TeX, the address is shown in angle brackets, preceded by
  487. the text to display if any.  In HTML output, `@email' produces a
  488. `mailto' link that usually brings up a mail composition window.  For
  489. example:
  490.  
  491.      Send bug reports to @email{bug-texinfo@@prep.ai.mit.edu}.
  492.      Send suggestions to the @email{bug-texinfo@@prep.ai.mit.edu, same place}.
  493.    produces
  494.      Send bug reports to <bug-texinfo@prep.ai.mit.edu>.
  495.      Send suggestions to the same place <bug-texinfo@prep.ai.mit.edu>.
  496.  
  497. 
  498. File: texinfo.info,  Node: Emphasis,  Prev: Indicating,  Up: Marking Text
  499.  
  500. Emphasizing Text
  501. ================
  502.  
  503.   Usually, Texinfo changes the font to mark words in the text according
  504. to what category the words belong to; an example is the `@code' command.
  505. Most often, this is the best way to mark words.  However, sometimes you
  506. will want to emphasize text without indicating a category.  Texinfo has
  507. two commands to do this.  Also, Texinfo has several commands that
  508. specify the font in which TeX will typeset text.  These commands have
  509. no affect on Info and only one of them, the `@r' command, has any
  510. regular use.
  511.  
  512. * Menu:
  513.  
  514. * emph & strong::               How to emphasize text in Texinfo.
  515. * Smallcaps::                   How to use the small caps font.
  516. * Fonts::                       Various font commands for printed output.
  517. * Customized Highlighting::     How to define highlighting commands.
  518.  
  519. 
  520. File: texinfo.info,  Node: emph & strong,  Next: Smallcaps,  Prev: Emphasis,  Up: Emphasis
  521.  
  522. `@emph'{TEXT} and `@strong'{TEXT}
  523. ---------------------------------
  524.  
  525.   The `@emph' and `@strong' commands are for emphasis; `@strong' is
  526. stronger.  In printed output, `@emph' produces *italics* and `@strong'
  527. produces *bold*.
  528.  
  529.   For example,
  530.  
  531.      @quotation
  532.      @strong{Caution:} @samp{rm * .[^.]*} removes @emph{all}
  533.      files in the directory.
  534.      @end quotation
  535.  
  536. produces:
  537.  
  538.           *Caution*: `rm * .[^.]*' removes *all*
  539.           files in the directory.
  540.  
  541.   The `@strong' command is seldom used except to mark what is, in
  542. effect, a typographical element, such as the word `Caution' in the
  543. preceding example.
  544.  
  545.   In the Info file, both `@emph' and `@strong' put asterisks around the
  546. text.
  547.  
  548.      *Caution:* Do not use `@emph' or `@strong' with the word `Note';
  549.      Info will mistake the combination for a cross reference.  Use a
  550.      phrase such as *Please note* or *Caution* instead.
  551.  
  552. 
  553. File: texinfo.info,  Node: Smallcaps,  Next: Fonts,  Prev: emph & strong,  Up: Emphasis
  554.  
  555. `@sc'{TEXT}: The Small Caps Font
  556. --------------------------------
  557.  
  558.   Use the `@sc' command to set text in the printed output in a small
  559. caps font and set text in the Info file in upper case letters.
  560.  
  561.   Write the text between braces in lower case, like this:
  562.  
  563.      The @sc{acm} and @sc{ieee} are technical societies.
  564.  
  565. This produces:
  566.  
  567.      The ACM and IEEE are technical societies.
  568.  
  569.   TeX typesets the small caps font in a manner that prevents the
  570. letters from `jumping out at you on the page'.  This makes small caps
  571. text easier to read than text in all upper case.  The Info formatting
  572. commands set all small caps text in upper case.
  573.  
  574.   If the text between the braces of an `@sc' command is upper case, TeX
  575. typesets in full-size capitals.  Use full-size capitals sparingly.
  576.  
  577.   You may also use the small caps font for a jargon word such as ATO (a
  578. NASA word meaning `abort to orbit').
  579.  
  580.   There are subtleties to using the small caps font with a jargon word
  581. such as CDR, a word used in Lisp programming.  In this case, you should
  582. use the small caps font when the word refers to the second and
  583. subsequent elements of a list (the CDR of the list), but you should use
  584. `@code' when the word refers to the Lisp function of the same spelling.
  585.  
  586. 
  587. File: texinfo.info,  Node: Fonts,  Next: Customized Highlighting,  Prev: Smallcaps,  Up: Emphasis
  588.  
  589. Fonts for Printing, Not Info
  590. ----------------------------
  591.  
  592.   Texinfo provides four font commands that specify font changes in the
  593. printed manual but have no effect in the Info file.  `@i' requests
  594. italic font (in some versions of TeX, a slanted font is used), `@b'
  595. requests bold face, `@t' requests the fixed-width, typewriter-style
  596. font used by `@code', and `@r' requests a roman font, which is the
  597. usual font in which text is printed.  All four commands apply to an
  598. argument that follows, surrounded by braces.
  599.  
  600.   Only the `@r' command has much use: in example programs, you can use
  601. the `@r' command to convert code comments from the fixed-width font to
  602. a roman font.  This looks better in printed output.
  603.  
  604.   For example,
  605.  
  606.      @lisp
  607.      (+ 2 2)    ; @r{Add two plus two.}
  608.      @end lisp
  609.  
  610. produces
  611.  
  612.      (+ 2 2)    ; Add two plus two.
  613.  
  614.   If possible, you should avoid using the other three font commands.  If
  615. you need to use one, it probably indicates a gap in the Texinfo
  616. language.
  617.  
  618. 
  619. File: texinfo.info,  Node: Customized Highlighting,  Prev: Fonts,  Up: Emphasis
  620.  
  621. Customized Highlighting
  622. -----------------------
  623.  
  624.   You can use regular TeX commands inside of `@iftex' ...  `@end iftex'
  625. to create your own customized highlighting commands for Texinfo.  The
  626. easiest way to do this is to equate your customized commands with
  627. pre-existing commands, such as those for italics.  Such new commands
  628. work only with TeX.
  629.  
  630.   You can use the `@definfoenclose' command inside of `@ifinfo' ...
  631. `@end ifinfo' to define commands for Info with the same names as new
  632. commands for TeX.  `@definfoenclose' creates new commands for Info that
  633. mark text by enclosing it in strings that precede and follow the text.
  634. (1) (*note Customized Highlighting-Footnotes::)
  635.  
  636.   Here is how to create a new @-command called `@phoo' that causes TeX
  637. to typeset its argument in italics and causes Info to display the
  638. argument between `//' and `\\'.
  639.  
  640.   For TeX, write the following to equate the `@phoo' command with the
  641. existing `@i' italics command:
  642.  
  643.      @iftex
  644.      @global@let@phoo=@i
  645.      @end iftex
  646.  
  647. This defines `@phoo' as a command that causes TeX to typeset the
  648. argument to `@phoo' in italics.  `@global@let' tells TeX to equate the
  649. next argument with the argument that follows the equals sign.
  650.  
  651.   For Info, write the following to tell the Info formatters to enclose
  652. the argument between `//' and `\\':
  653.  
  654.      @ifinfo
  655.      @definfoenclose phoo, //, \\
  656.      @end ifinfo
  657.  
  658. Write the `@definfoenclose' command on a line and follow it with three
  659. arguments separated by commas (commas are used as separators in an
  660. `@node' line in the same way).
  661.  
  662.    * The first argument to `@definfoenclose' is the @-command name
  663.      *without* the `@';
  664.  
  665.    * the second argument is the Info start delimiter string; and,
  666.  
  667.    * the third argument is the Info end delimiter string.
  668.  
  669. The latter two arguments enclose the highlighted text in the Info file.
  670. A delimiter string may contain spaces.  Neither the start nor end
  671. delimiter is required.  However, if you do not provide a start
  672. delimiter, you must follow the command name with two commas in a row;
  673. otherwise, the Info formatting commands will misinterpret the end
  674. delimiter string as a start delimiter string.
  675.  
  676.   After you have defined `@phoo' both for TeX and for Info, you can
  677. then write `@phoo{bar}' to see `//bar\\' in Info and see `bar' in
  678. italics in printed output.
  679.  
  680.   Note that each definition applies to its own formatter: one for TeX,
  681. the other for Info.
  682.  
  683.   Here is another example:
  684.  
  685.      @ifinfo
  686.      @definfoenclose headword, , :
  687.      @end ifinfo
  688.      @iftex
  689.      @global@let@headword=@b
  690.      @end iftex
  691.  
  692. This defines `@headword' as an Info formatting command that inserts
  693. nothing before and a colon after the argument and as a TeX formatting
  694. command to typeset its argument in bold.
  695.  
  696. 
  697. File: texinfo.info,  Node: Customized Highlighting-Footnotes,  Up: Customized Highlighting
  698.  
  699.   (1) Currently, `@definfoenclose' works only with
  700. `texinfo-format-buffer' and `texinfo-format-region', not with
  701. `makeinfo'.
  702.  
  703. 
  704. File: texinfo.info,  Node: Quotations and Examples,  Next: Lists and Tables,  Prev: Marking Text,  Up: Top
  705.  
  706. Quotations and Examples
  707. ***********************
  708.  
  709.   Quotations and examples are blocks of text consisting of one or more
  710. whole paragraphs that are set off from the bulk of the text and treated
  711. differently.  They are usually indented.
  712.  
  713.   In Texinfo, you always begin a quotation or example by writing an
  714. @-command at the beginning of a line by itself, and end it by writing
  715. an `@end' command that is also at the beginning of a line by itself.
  716. For instance, you begin an example by writing `@example' by itself at
  717. the beginning of a line and end the example by writing `@end example'
  718. on a line by itself, at the beginning of that line.
  719.  
  720. * Menu:
  721.  
  722. * Block Enclosing Commands::    Use different constructs for
  723.                                   different purposes.
  724. * quotation::                   How to write a quotation.
  725. * example::                     How to write an example in a fixed-width font.
  726. * noindent::                    How to prevent paragraph indentation.
  727. * Lisp Example::                How to illustrate Lisp code.
  728. * smallexample & smalllisp::    Forms for the `@smallbook' option.
  729. * display::                     How to write an example in the current font.
  730. * format::                      How to write an example that does not narrow
  731.                                   the margins.
  732. * exdent::                      How to undo the indentation of a line.
  733. * flushleft & flushright::      How to push text flushleft or flushright.
  734. * cartouche::                   How to draw cartouches around examples.
  735.  
  736. 
  737. File: texinfo.info,  Node: Block Enclosing Commands,  Next: quotation,  Prev: Quotations and Examples,  Up: Quotations and Examples
  738.  
  739. The Block Enclosing Commands
  740. ============================
  741.  
  742.   Here are commands for quotations and examples:
  743.  
  744. `@quotation'
  745.      Indicate text that is quoted. The text is filled, indented, and
  746.      printed in a roman font by default.
  747.  
  748. `@example'
  749.      Illustrate code, commands, and the like. The text is printed in a
  750.      fixed-width font, and indented but not filled.
  751.  
  752. `@lisp'
  753.      Illustrate Lisp code. The text is printed in a fixed-width font,
  754.      and indented but not filled.
  755.  
  756. `@smallexample'
  757.      Illustrate code, commands, and the like.  Similar to `@example',
  758.      except that in TeX this command typesets text in a smaller font
  759.      for the smaller `@smallbook' format than for the 8.5 by 11 inch
  760.      format.
  761.  
  762. `@smalllisp'
  763.      Illustrate Lisp code.  Similar to `@lisp', except that in TeX this
  764.      command typesets text in a smaller font for the smaller
  765.      `@smallbook' format than for the 8.5 by 11 inch format.
  766.  
  767. `@display'
  768.      Display illustrative text.  The text is indented but not filled,
  769.      and no font is specified (so, by default, the font is roman).
  770.  
  771. `@format'
  772.      Print illustrative text.  The text is not indented and not filled
  773.      and no font is specified (so, by default, the font is roman).
  774.  
  775.   The `@exdent' command is used within the above constructs to undo the
  776. indentation of a line.
  777.  
  778.   The `@flushleft' and `@flushright' commands are used to line up the
  779. left or right margins of unfilled text.
  780.  
  781.   The `@noindent' command may be used after one of the above constructs
  782. to prevent the following text from being indented as a new paragraph.
  783.  
  784.   You can use the `@cartouche' command within one of the above
  785. constructs to highlight the example or quotation by drawing a box with
  786. rounded corners around it.  (The `@cartouche' command affects only the
  787. printed manual; it has no effect in the Info file; see *Note Drawing
  788. Cartouches Around Examples: cartouche.)
  789.  
  790. 
  791. File: texinfo.info,  Node: quotation,  Next: example,  Prev: Block Enclosing Commands,  Up: Quotations and Examples
  792.  
  793. `@quotation'
  794. ============
  795.  
  796.   The text of a quotation is processed normally except that:
  797.  
  798.    * the margins are closer to the center of the page, so the whole of
  799.      the quotation is indented;
  800.  
  801.    * the first lines of paragraphs are indented no more than other
  802.      lines;
  803.  
  804.    * in the printed output, interparagraph spacing is reduced.
  805.  
  806.      This is an example of text written between an `@quotation' command
  807.      and an `@end quotation' command.  An `@quotation' command is most
  808.      often used to indicate text that is excerpted from another (real
  809.      or hypothetical) printed work.
  810.  
  811.   Write an `@quotation' command as text on a line by itself.  This line
  812. will disappear from the output.  Mark the end of the quotation with a
  813. line beginning with and containing only `@end quotation'.  The `@end
  814. quotation' line will likewise disappear from the output.  Thus, the
  815. following,
  816.  
  817.      @quotation
  818.      This is
  819.      a foo.
  820.      @end quotation
  821.  
  822. produces
  823.  
  824.      This is a foo.
  825.  
  826. 
  827. File: texinfo.info,  Node: example,  Next: noindent,  Prev: quotation,  Up: Quotations and Examples
  828.  
  829. `@example'
  830. ==========
  831.  
  832.   The `@example' command is used to indicate an example that is not
  833. part of the running text, such as computer input or output.
  834.  
  835.      This is an example of text written between an
  836.      `@example' command
  837.      and an `@end example' command.
  838.      The text is indented but not filled.
  839.      
  840.      In the printed manual, the text is typeset in a
  841.      fixed-width font, and extra spaces and blank lines are
  842.      significant.  In the Info file, an analogous result is
  843.      obtained by indenting each line with five spaces.
  844.  
  845.   Write an `@example' command at the beginning of a line by itself.
  846. This line will disappear from the output.  Mark the end of the example
  847. with an `@end example' command, also written at the beginning of a line
  848. by itself.  The `@end example' will disappear from the output.
  849.  
  850.   For example,
  851.  
  852.      @example
  853.      mv foo bar
  854.      @end example
  855.  
  856. produces
  857.  
  858.      mv foo bar
  859.  
  860.   Since the lines containing `@example' and `@end example' will
  861. disappear, you should put a blank line before the `@example' and
  862. another blank line after the `@end example'.  (Remember that blank
  863. lines between the beginning `@example' and the ending `@end example'
  864. will appear in the output.)
  865.  
  866.      *Caution:* Do not use tabs in the lines of an example (or anywhere
  867.      else in Texinfo, for that matter)!  TeX treats tabs as single
  868.      spaces, and that is not what they look like.  This is a problem
  869.      with TeX.  (If necessary, in Emacs, you can use `M-x untabify' to
  870.      convert tabs in a region to multiple spaces.)
  871.  
  872.   Examples are often, logically speaking, "in the middle" of a
  873. paragraph, and the text continues after an example should not be
  874. indented.  The `@noindent' command prevents a piece of text from being
  875. indented as if it were a new paragraph.  (*Note noindent::.)
  876.  
  877.   (The `@code' command is used for examples of code that are embedded
  878. within sentences, not set off from preceding and following text.  *Note
  879. `@code': code.)
  880.  
  881. 
  882. File: texinfo.info,  Node: noindent,  Next: Lisp Example,  Prev: example,  Up: Quotations and Examples
  883.  
  884. `@noindent'
  885. ===========
  886.  
  887.   An example or other inclusion can break a paragraph into segments.
  888. Ordinarily, the formatters indent text that follows an example as a new
  889. paragraph.  However, you can prevent this by writing `@noindent' at the
  890. beginning of a line by itself preceding the continuation text.
  891.  
  892.   For example:
  893.  
  894.      @example
  895.      This is an example
  896.      @end example
  897.      
  898.      @noindent
  899.      This line is not indented.  As you can see, the
  900.      beginning of the line is fully flush left with the line
  901.      that follows after it.  (This whole example is between
  902.      @code{@@display} and @code{@@end display}.)
  903.  
  904. produces
  905.  
  906.           This is an example
  907.      
  908.      
  909.      This line is not indented.  As you can see, the
  910.      beginning of the line is fully flush left with the line
  911.      that follows after it.  (This whole example is between
  912.      `@display' and `@end display'.)
  913.  
  914.   To adjust the number of blank lines properly in the Info file output,
  915. remember that the line containing `@noindent' does not generate a blank
  916. line, and neither does the `@end example' line.
  917.  
  918.   In the Texinfo source file for this manual, each line that says
  919. `produces' is preceded by a line containing `@noindent'.
  920.  
  921.   Do not put braces after an `@noindent' command; they are not
  922. necessary, since `@noindent' is a command used outside of paragraphs
  923. (*note Command Syntax::.).
  924.  
  925. 
  926. File: texinfo.info,  Node: Lisp Example,  Next: smallexample & smalllisp,  Prev: noindent,  Up: Quotations and Examples
  927.  
  928. `@lisp'
  929. =======
  930.  
  931.   The `@lisp' command is used for Lisp code.  It is synonymous with the
  932. `@example' command.
  933.  
  934.      This is an example of text written between an
  935.      `@lisp' command and an `@end lisp' command.
  936.  
  937.   Use `@lisp' instead of `@example' to preserve information regarding
  938. the nature of the example.  This is useful, for example, if you write a
  939. function that evaluates only and all the Lisp code in a Texinfo file.
  940. Then you can use the Texinfo file as a Lisp library.(1) (*note Lisp
  941. Example-Footnotes::)
  942.  
  943.   Mark the end of `@lisp' with `@end lisp' on a line by itself.
  944.  
  945. 
  946. File: texinfo.info,  Node: Lisp Example-Footnotes,  Up: Lisp Example
  947.  
  948.   (1) It would be straightforward to extend Texinfo to work in a
  949. similar fashion for C, Fortran, or other languages.
  950.  
  951. 
  952. File: texinfo.info,  Node: smallexample & smalllisp,  Next: display,  Prev: Lisp Example,  Up: Quotations and Examples
  953.  
  954. `@smallexample' and `@smalllisp'
  955. ================================
  956.  
  957.   In addition to the regular `@example' and `@lisp' commands, Texinfo
  958. has two other "example-style" commands.  These are the `@smallexample'
  959. and `@smalllisp' commands.  Both these commands are designed for use
  960. with the `@smallbook' command that causes TeX to produce a printed
  961. manual in a 7 by 9.25 inch format rather than the regular 8.5 by 11
  962. inch format.
  963.  
  964.   In TeX, the `@smallexample' and `@smalllisp' commands typeset text in
  965. a smaller font for the smaller `@smallbook' format than for the 8.5 by
  966. 11 inch format.  Consequently, many examples containing long lines fit
  967. in a narrower, `@smallbook' page without needing to be shortened.  Both
  968. commands typeset in the normal font size when you format for the 8.5 by
  969. 11 inch size; indeed, in this situation, the `@smallexample' and
  970. `@smalllisp' commands are defined to be the `@example' and `@lisp'
  971. commands.
  972.  
  973.   In Info, the `@smallexample' and `@smalllisp' commands are equivalent
  974. to the `@example' and `@lisp' commands, and work exactly the same.
  975.  
  976.   Mark the end of `@smallexample' or `@smalllisp' with `@end
  977. smallexample' or `@end smalllisp', respectively.
  978.  
  979.      This is an example of text written between `@smallexample' and
  980.      `@end smallexample'.  In Info and in an 8.5 by 11 inch manual,
  981.      this text appears in its normal size; but in a 7 by 9.25 inch manual,
  982.      this text appears in a smaller font.
  983.  
  984.   The `@smallexample' and `@smalllisp' commands make it easier to
  985. prepare smaller format manuals without forcing you to edit examples by
  986. hand to fit them onto narrower pages.
  987.  
  988.   As a general rule, a printed document looks better if you write all
  989. the examples in a chapter consistently in `@example' or in
  990. `@smallexample'.  Only occasionally should you mix the two formats.
  991.  
  992.   *Note Printing "Small" Books: smallbook, for more information about
  993. the `@smallbook' command.
  994.  
  995. 
  996. File: texinfo.info,  Node: display,  Next: format,  Prev: smallexample & smalllisp,  Up: Quotations and Examples
  997.  
  998. `@display'
  999. ==========
  1000.  
  1001.   The `@display' command begins a kind of example.  It is like the
  1002. `@example' command except that, in a printed manual, `@display' does
  1003. not select the fixed-width font.  In fact, it does not specify the font
  1004. at all, so that the text appears in the same font it would have
  1005. appeared in without the `@display' command.
  1006.  
  1007.      This is an example of text written between an `@display' command
  1008.      and an `@end display' command.  The `@display' command
  1009.      indents the text, but does not fill it.
  1010.  
  1011. 
  1012. File: texinfo.info,  Node: format,  Next: exdent,  Prev: display,  Up: Quotations and Examples
  1013.  
  1014. `@format'
  1015. =========
  1016.  
  1017.   The `@format' command is similar to `@example' except that, in the
  1018. printed manual, `@format' does not select the fixed-width font and does
  1019. not narrow the margins.
  1020.  
  1021. This is an example of text written between an `@format' command
  1022. and an `@end format' command.  As you can see
  1023. from this example,
  1024. the `@format' command does not fill the text.
  1025.  
  1026. 
  1027. File: texinfo.info,  Node: exdent,  Next: flushleft & flushright,  Prev: format,  Up: Quotations and Examples
  1028.  
  1029. `@exdent': Undoing a Line's Indentation
  1030. =======================================
  1031.  
  1032.   The `@exdent' command removes any indentation a line might have.  The
  1033. command is written at the beginning of a line and applies only to the
  1034. text that follows the command that is on the same line.  Do not use
  1035. braces around the text.  In a printed manual, the text on an `@exdent'
  1036. line is printed in the roman font.
  1037.  
  1038.   `@exdent' is usually used within examples.  Thus,
  1039.  
  1040.      @example
  1041.      This line follows an @@example command.
  1042.      @exdent This line is exdented.
  1043.      This line follows the exdented line.
  1044.      The @@end example comes on the next line.
  1045.      @end group
  1046.  
  1047. produces
  1048.  
  1049.      This line follows an @example command.
  1050. This line is exdented.
  1051.      This line follows the exdented line.
  1052.      The @end example comes on the next line.
  1053.  
  1054.   In practice, the `@exdent' command is rarely used.  Usually, you
  1055. un-indent text by ending the example and returning the page to its
  1056. normal width.
  1057.  
  1058. 
  1059. File: texinfo.info,  Node: flushleft & flushright,  Next: cartouche,  Prev: exdent,  Up: Quotations and Examples
  1060.  
  1061. `@flushleft' and `@flushright'
  1062. ==============================
  1063.  
  1064.   The `@flushleft' and `@flushright' commands line up the ends of lines
  1065. on the left and right margins of a page, but do not fill the text.  The
  1066. commands are written on lines of their own, without braces.  The
  1067. `@flushleft' and `@flushright' commands are ended by `@end flushleft'
  1068. and `@end flushright' commands on lines of their own.
  1069.  
  1070.   For example,
  1071.  
  1072.      @flushleft
  1073.      This text is
  1074.      written flushleft.
  1075.      @end flushleft
  1076.  
  1077. produces
  1078.  
  1079.      This text is
  1080.      written flushleft.
  1081.  
  1082.   `@flushright' produces the type of indentation often used in the
  1083. return address of letters.  For example,
  1084.  
  1085.      @flushright
  1086.      Here is an example of text written
  1087.      flushright.  The @code{@flushright} command
  1088.      right justifies every line but leaves the
  1089.      left end ragged.
  1090.      @end flushright
  1091.  
  1092. produces
  1093.  
  1094.                                      Here is an example of text written
  1095.                                  flushright.  The `@flushright' command
  1096.                               right justifies every line but leaves the
  1097.                                                        left end ragged.
  1098.  
  1099. 
  1100. File: texinfo.info,  Node: cartouche,  Prev: flushleft & flushright,  Up: Quotations and Examples
  1101.  
  1102. Drawing Cartouches Around Examples
  1103. ==================================
  1104.  
  1105.   In a printed manual, the `@cartouche' command draws a box with
  1106. rounded corners around its contents.  You can use this command to
  1107. further highlight an example or quotation.  For instance, you could
  1108. write a manual in which one type of example is surrounded by a cartouche
  1109. for emphasis.
  1110.  
  1111.   The `@cartouche' command affects only the printed manual; it has no
  1112. effect in the Info file.
  1113.  
  1114.   For example,
  1115.  
  1116.      @example
  1117.      @cartouche
  1118.      % pwd
  1119.      /usr/local/share/emacs
  1120.      @end cartouche
  1121.      @end example
  1122.  
  1123. surrounds the two-line example with a box with rounded corners, in the
  1124. printed manual.
  1125.  
  1126. 
  1127. File: texinfo.info,  Node: Lists and Tables,  Next: Indices,  Prev: Quotations and Examples,  Up: Top
  1128.  
  1129. Lists and Tables
  1130. ****************
  1131.  
  1132.   Texinfo has several ways of making lists and tables.  Lists can be
  1133. bulleted or numbered; two-column tables can highlight the items in the
  1134. first column; multi-column tables are also supported.
  1135.  
  1136. * Menu:
  1137.  
  1138. * Introducing Lists::           Texinfo formats lists for you.
  1139. * itemize::                     How to construct a simple list.
  1140. * enumerate::                   How to construct a numbered list.
  1141. * Two-column Tables::           How to construct a two-column table.
  1142. * Multi-column Tables::         How to construct generalized tables.
  1143.  
  1144. 
  1145. File: texinfo.info,  Node: Introducing Lists,  Next: itemize,  Prev: Lists and Tables,  Up: Lists and Tables
  1146.  
  1147. Introducing Lists
  1148. =================
  1149.  
  1150.   Texinfo automatically indents the text in lists or tables, and numbers
  1151. an enumerated list.  This last feature is useful if you modify the
  1152. list, since you do not need to renumber it yourself.
  1153.  
  1154.   Numbered lists and tables begin with the appropriate @-command at the
  1155. beginning of a line, and end with the corresponding `@end' command on a
  1156. line by itself.  The table and itemized-list commands also require that
  1157. you write formatting information on the same line as the beginning
  1158. @-command.
  1159.  
  1160.   Begin an enumerated list, for example, with an `@enumerate' command
  1161. and end the list with an `@end enumerate' command.  Begin an itemized
  1162. list with an `@itemize' command, followed on the same line by a
  1163. formatting command such as `@bullet', and end the list with an `@end
  1164. itemize' command.
  1165.  
  1166.   Precede each element of a list with an `@item' or `@itemx' command.
  1167.  
  1168. Here is an itemized list of the different kinds of table and lists:
  1169.  
  1170.    * Itemized lists with and without bullets.
  1171.  
  1172.    * Enumerated lists, using numbers or letters.
  1173.  
  1174.    * Two-column tables with highlighting.
  1175.  
  1176. Here is an enumerated list with the same items:
  1177.  
  1178.   1. Itemized lists with and without bullets.
  1179.  
  1180.   2. Enumerated lists, using numbers or letters.
  1181.  
  1182.   3. Two-column tables with highlighting.
  1183.  
  1184. And here is a two-column table with the same items and their @-commands:
  1185.  
  1186. `@itemize'
  1187.      Itemized lists with and without bullets.
  1188.  
  1189. `@enumerate'
  1190.      Enumerated lists, using numbers or letters.
  1191.  
  1192. `@table'
  1193. `@ftable'
  1194. `@vtable'
  1195.      Two-column tables with indexing.
  1196.  
  1197. 
  1198. File: texinfo.info,  Node: itemize,  Next: enumerate,  Prev: Introducing Lists,  Up: Lists and Tables
  1199.  
  1200. Making an Itemized List
  1201. =======================
  1202.  
  1203.   The `@itemize' command produces sequences of indented paragraphs,
  1204. with a bullet or other mark inside the left margin at the beginning of
  1205. each paragraph for which such a mark is desired.
  1206.  
  1207.   Begin an itemized list by writing `@itemize' at the beginning of a
  1208. line.  Follow the command, on the same line, with a character or a
  1209. Texinfo command that generates a mark.  Usually, you will write
  1210. `@bullet' after `@itemize', but you can use `@minus', or any character
  1211. or any special symbol that results in a single character in the Info
  1212. file.  (When you write `@bullet' or `@minus' after an `@itemize'
  1213. command, you may omit the `{}'.)
  1214.  
  1215.   Write the text of the indented paragraphs themselves after the
  1216. `@itemize', up to another line that says `@end itemize'.
  1217.  
  1218.   Before each paragraph for which a mark in the margin is desired, write
  1219. a line that says just `@item'.  Do not write any other text on this
  1220. line.
  1221.  
  1222.   Usually, you should put a blank line before an `@item'.  This puts a
  1223. blank line in the Info file. (TeX inserts the proper interline
  1224. whitespace in either case.)  Except when the entries are very brief,
  1225. these blank lines make the list look better.
  1226.  
  1227.   Here is an example of the use of `@itemize', followed by the output
  1228. it produces.  Note that `@bullet' produces an `*' in Info and a round
  1229. dot in TeX.
  1230.  
  1231.      @itemize @bullet
  1232.      @item
  1233.      Some text for foo.
  1234.      
  1235.      @item
  1236.      Some text
  1237.      for bar.
  1238.      @end itemize
  1239.  
  1240. This produces:
  1241.  
  1242.         * Some text for foo.
  1243.  
  1244.         * Some text for bar.
  1245.  
  1246.   Itemized lists may be embedded within other itemized lists.  Here is a
  1247. list marked with dashes embedded in a list marked with bullets:
  1248.  
  1249.      @itemize @bullet
  1250.      @item
  1251.      First item.
  1252.      
  1253.      @itemize @minus
  1254.      @item
  1255.      Inner item.
  1256.      
  1257.      @item
  1258.      Second inner item.
  1259.      @end itemize
  1260.      
  1261.      @item
  1262.      Second outer item.
  1263.      @end itemize
  1264.  
  1265. This produces:
  1266.  
  1267.         * First item.
  1268.  
  1269.              - Inner item.
  1270.  
  1271.              - Second inner item.
  1272.  
  1273.         * Second outer item.
  1274.  
  1275. 
  1276. File: texinfo.info,  Node: enumerate,  Next: Two-column Tables,  Prev: itemize,  Up: Lists and Tables
  1277.  
  1278. Making a Numbered or Lettered List
  1279. ==================================
  1280.  
  1281.   `@enumerate' is like `@itemize' (*note `@itemize': itemize.), except
  1282. that the labels on the items are successive integers or letters instead
  1283. of bullets.
  1284.  
  1285.   Write the `@enumerate' command at the beginning of a line.  The
  1286. command does not require an argument, but accepts either a number or a
  1287. letter as an option.  Without an argument, `@enumerate' starts the list
  1288. with the number `1'.  With a numeric argument, such as `3', the command
  1289. starts the list with that number.  With an upper or lower case letter,
  1290. such as `a' or `A', the command starts the list with that letter.
  1291.  
  1292.   Write the text of the enumerated list in the same way you write an
  1293. itemized list: put `@item' on a line of its own before the start of
  1294. each paragraph that you want enumerated.  Do not write any other text
  1295. on the line beginning with `@item'.
  1296.  
  1297.   You should put a blank line between entries in the list.  This
  1298. generally makes it easier to read the Info file.
  1299.  
  1300.   Here is an example of `@enumerate' without an argument:
  1301.  
  1302.      @enumerate
  1303.      @item
  1304.      Underlying causes.
  1305.      
  1306.      @item
  1307.      Proximate causes.
  1308.      @end enumerate
  1309.  
  1310. This produces:
  1311.  
  1312.   1. Underlying causes.
  1313.  
  1314.   2. Proximate causes.
  1315.  
  1316.   Here is an example with an argument of `3':
  1317.  
  1318.      @enumerate 3
  1319.      @item
  1320.      Predisposing causes.
  1321.      
  1322.      @item
  1323.      Precipitating causes.
  1324.      
  1325.      @item
  1326.      Perpetuating causes.
  1327.      @end enumerate
  1328.  
  1329. This produces:
  1330.  
  1331.   3. Predisposing causes.
  1332.  
  1333.   4. Precipitating causes.
  1334.  
  1335.   5. Perpetuating causes.
  1336.  
  1337.   Here is a brief summary of the alternatives.  The summary is
  1338. constructed using `@enumerate' with an argument of `a'.
  1339.  
  1340.   a. `@enumerate'
  1341.  
  1342.      Without an argument, produce a numbered list, starting with the
  1343.      number 1.
  1344.  
  1345.   b. `@enumerate POSITIVE-INTEGER'
  1346.  
  1347.      With a (positive) numeric argument, start a numbered list with that
  1348.      number.  You can use this to continue a list that you interrupted
  1349.      with other text.
  1350.  
  1351.   c. `@enumerate UPPER-CASE-LETTER'
  1352.  
  1353.      With an upper case letter as argument, start a list in which each
  1354.      item is marked by a letter, beginning with that upper case letter.
  1355.  
  1356.   d. `@enumerate LOWER-CASE-LETTER'
  1357.  
  1358.      With a lower case letter as argument, start a list in which each
  1359.      item is marked by a letter, beginning with that lower case letter.
  1360.  
  1361.   You can also nest enumerated lists, as in an outline.
  1362.  
  1363. 
  1364. File: texinfo.info,  Node: Two-column Tables,  Next: Multi-column Tables,  Prev: enumerate,  Up: Lists and Tables
  1365.  
  1366. Making a Two-column Table
  1367. =========================
  1368.  
  1369.   `@table' is similar to `@itemize' (*note `@itemize': itemize.), but
  1370. allows you to specify a name or heading line for each item.  The
  1371. `@table' command is used to produce two-column tables, and is
  1372. especially useful for glossaries, explanatory exhibits, and
  1373. command-line option summaries.
  1374.  
  1375. * Menu:
  1376.  
  1377. * table::                       How to construct a two-column table.
  1378. * ftable vtable::               Automatic indexing for two-column tables.
  1379. * itemx::                       How to put more entries in the first column.
  1380.  
  1381. 
  1382. File: texinfo.info,  Node: table,  Next: ftable vtable,  Prev: Two-column Tables,  Up: Two-column Tables
  1383.  
  1384. Using the `@table' Command
  1385. --------------------------
  1386.  
  1387.   Use the `@table' command to produce two-column tables.
  1388.  
  1389.   Write the `@table' command at the beginning of a line and follow it
  1390. on the same line with an argument that is a Texinfo "indicating"
  1391. command such as `@code', `@samp', `@var', or `@kbd' (*note
  1392. Indicating::.).  Although these commands are usually followed by
  1393. arguments in braces, in this case you use the command name without an
  1394. argument because `@item' will supply the argument.  This command will
  1395. be applied to the text that goes into the first column of each item and
  1396. determines how it will be highlighted.  For example, `@code' will cause
  1397. the text in the first column to be highlighted with an `@code' command.
  1398. (We recommend `@code' for `@table''s of command-line options.)
  1399.  
  1400.   You may also choose to use the `@asis' command as an argument to
  1401. `@table'.  `@asis' is a command that does nothing; if you use this
  1402. command after `@table', TeX and the Info formatting commands output the
  1403. first column entries without added highlighting ("as is").
  1404.  
  1405.   (The `@table' command may work with other commands besides those
  1406. listed here.  However, you can only use commands that normally take
  1407. arguments in braces.)
  1408.  
  1409.   Begin each table entry with an `@item' command at the beginning of a
  1410. line.  Write the first column text on the same line as the `@item'
  1411. command.  Write the second column text on the line following the
  1412. `@item' line and on subsequent lines.  (You do not need to type
  1413. anything for an empty second column entry.)  You may write as many
  1414. lines of supporting text as you wish, even several paragraphs.  But
  1415. only text on the same line as the `@item' will be placed in the first
  1416. column.
  1417.  
  1418.   Normally, you should put a blank line before an `@item' line.  This
  1419. puts a blank like in the Info file.  Except when the entries are very
  1420. brief, a blank line looks better.
  1421.  
  1422.   The following table, for example, highlights the text in the first
  1423. column with an `@samp' command:
  1424.  
  1425.      @table @samp
  1426.      @item foo
  1427.      This is the text for
  1428.      @samp{foo}.
  1429.      
  1430.      @item bar
  1431.      Text for @samp{bar}.
  1432.      @end table
  1433.  
  1434. This produces:
  1435.  
  1436. `foo'
  1437.      This is the text for `foo'.
  1438.  
  1439. `bar'
  1440.      Text for `bar'.
  1441.  
  1442.   If you want to list two or more named items with a single block of
  1443. text, use the `@itemx' command.  (*Note `@itemx': itemx.)
  1444.  
  1445.